home *** CD-ROM | disk | FTP | other *** search
/ HyperLib 1997 Winter - Disc 1 / HYPERLIB-1997-Winter-CD1.ISO.7z / HYPERLIB-1997-Winter-CD1.ISO / オンラインウェア / UTIL / PL 2.0 SupplementDoc Folder.sit / PL 2.0 SupplementDoc Folder / Documentation / Chapter 26. Loop < prev    next >
Text File  |  1995-03-28  |  69KB  |  1,875 lines
  1. Common Lisp the Language, 2nd Edition
  2. -------------------------------------------------------------------------------
  3.  
  4. 26. Loop
  5.  
  6. By Jon L White
  7.  
  8. [change_begin]
  9. PREFACE: X3J13 voted in January 1989 (LOOP-FACILITY)   to adopt an extended
  10. definition of the loop macro as a part of the forthcoming draft Common Lisp
  11. standard.
  12.  
  13. This chapter presents the bulk of the Common Lisp Loop Facility proposal,
  14. written by Jon L White. I have edited it only very lightly to conform to the
  15. overall style of this book and have inserted a small number of bracketed
  16. remarks, identified by the initials GLS. (See the Acknowledgments to this
  17. second edition for acknowledgments to others who contributed to the Loop
  18. Facility proposal.)
  19.  
  20.      - Guy L. Steele Jr.
  21.  
  22. [change_end]
  23. -------------------------------------------------------------------------------
  24.  
  25.    *  Introduction
  26.    *  How the Loop Facility Works
  27.    *  Parsing Loop Clauses
  28.         o  Order of Execution
  29.         o  Kinds of Loop Clauses
  30.         o  Loop Syntax
  31.    *  User Extensibility
  32.    *  Loop Constructs
  33.    *  Iteration Control
  34.    *  End-Test Control
  35.    *  Value Accumulation
  36.    *  Variable Initializations
  37.    *  Conditional Execution
  38.    *  Unconditional Execution
  39.    *  Miscellaneous Features
  40.         o  Data Types
  41.         o  Destructuring
  42.  
  43. -------------------------------------------------------------------------------
  44.  
  45. 26.1. Introduction
  46.  
  47. [change_begin]
  48. A loop is a series of expressions that are executed one or more times, a
  49. process known as iteration. The Loop Facility defines a variety of useful
  50. methods, indicated by loop keywords, to iterate and to accumulate values in a
  51. loop.
  52.  
  53. Loop keywords are not true Common Lisp keywords; they are symbols that are
  54. recognized by the Loop Facility and that provide such capabilities as
  55. controlling the direction of iteration, accumulating values inside the body of
  56. a loop, and evaluating expressions that precede or follow the loop body. If you
  57. do not use any loop keywords, the Loop Facility simply executes the loop body
  58. repeatedly.
  59. [change_end]
  60.  
  61. -------------------------------------------------------------------------------
  62.  
  63. 26.2. How the Loop Facility Works
  64.  
  65. [change_begin]
  66. The driving element of the Loop Facility is the loop macro. When Lisp
  67. encounters a loop macro call form, it invokes the Loop Facility and passes to
  68. it the loop clauses as a list of unevaluated forms, as with any macro. The loop
  69. clauses contain Common Lisp forms and loop keywords. The loop keywords are
  70. recognized by their symbol name, regardless of the packages that contain them.
  71. The loop macro translates the given form into Common Lisp code and returns the
  72. expanded form.
  73.  
  74. The expanded loop form is one or more lambda-expressions for the local binding
  75. of loop variables and a block and a tagbody that express a looping control
  76. structure. The variables established in the loop construct are bound as if by
  77. using let or lambda. Implementations can interleave the setting of initial
  78. values with the bindings. However, the assignment of the initial values is
  79. always calculated in the order specified by the user. A variable is thus
  80. sometimes bound to a harmless value of the correct data type, and then later in
  81. the prologue it is set to the true initial value by using setq.
  82.  
  83. The expanded form consists of three basic parts in the tagbody:
  84.  
  85.    *  The loop prologue contains forms that are executed before iteration
  86.      begins, such as initial settings of loop variables and possibly an initial
  87.      termination test.
  88.  
  89.    *  The loop body contains those forms that are executed during iteration,
  90.      including application-specific calculations, termination tests, and
  91.      variable stepping. Stepping is the process of assigning a variable the
  92.      next item in a series of items.
  93.  
  94.    *  The loop epilogue contains forms that are executed after iteration
  95.      terminates, such as code to return values from the loop.
  96.  
  97. Expansion of the loop macro produces an implicit block (named nil). Thus, the
  98. Common Lisp macro return and the special form return-from can be used to return
  99. values from a loop or to exit a loop.
  100.  
  101. Within the executable parts of loop clauses and around the entire loop form,
  102. you can still bind variables by using the Common Lisp special form let.
  103. [change_end]
  104.  
  105. -------------------------------------------------------------------------------
  106.  
  107. 26.3. Parsing Loop Clauses
  108.  
  109. [change_begin]
  110. The syntactic parts of a loop construct are called clauses; the scope of each
  111. clause is determined by the top-level parsing of that clause's keyword. The
  112. following example shows a loop construct with six clauses:
  113.  
  114. (loop for i from 1 to (compute-top-value)         ;First clause
  115.       while (not (unacceptable i))                ;Second clause
  116.       collect (square i)                          ;Third clause
  117.       do (format t "Working on ~D now" i)         ;Fourth clause
  118.       when (evenp i)                              ;Fifth clause
  119.         do (format t "~D is a non-odd number" i)
  120.       finally (format t "About to exit!"))        ;Sixth clause
  121.  
  122. Each loop keyword introduces either a compound loop clause or a simple loop
  123. clause that can consist of a loop keyword followed by a single Lisp form. The
  124. number of forms in a clause is determined by the loop keyword that begins the
  125. clause and by the auxiliary keywords in the clause. The keywords do, initially,
  126. and finally are the only loop keywords that can take any number of Lisp forms
  127. and group them as if in a single progn form.
  128.  
  129. Loop clauses can contain auxiliary keywords, which are sometimes called
  130. prepositions. For example, the first clause in the preceding code includes the
  131. prepositions from and to, which mark the value from which stepping begins and
  132. the value at which stepping ends.
  133. [change_end]
  134.  
  135. -------------------------------------------------------------------------------
  136.  
  137.    *  Order of Execution
  138.    *  Kinds of Loop Clauses
  139.    *  Loop Syntax
  140.  
  141. -------------------------------------------------------------------------------
  142.  
  143. 26.3.1. Order of Execution
  144.  
  145. [change_begin]
  146. With the exceptions listed below, clauses are executed in the loop body in the
  147. order in which they appear in the source. Execution is repeated until a clause
  148. terminates the loop or until a Common Lisp return, go, or throw form is
  149. encountered. The following actions are exceptions to the linear order of
  150. execution:
  151.  
  152.    *  All variables are initialized first, regardless of where the establishing
  153.      clauses appear in the source. The order of initialization follows the
  154.      order of these clauses.
  155.  
  156.    *  The code for any initially clauses is collected into one progn in the
  157.      order in which the clauses appear in the source. The collected code is
  158.      executed once in the loop prologue after any implicit variable
  159.      initializations.
  160.  
  161.    *  The code for any finally clauses is collected into one progn in the order
  162.      in which the clauses appear in the source. The collected code is executed
  163.      once in the loop epilogue before any implicit values from the accumulation
  164.      clauses are returned. Explicit returns anywhere in the source, however,
  165.      will exit the loop without executing the epilogue code.
  166.  
  167.    *  A with clause introduces a variable binding and an optional initial
  168.      value. The initial values are calculated in the order in which the with
  169.      clauses occur.
  170.  
  171.    *  Iteration control clauses implicitly perform the following actions:
  172.  
  173.         o  initializing variables
  174.  
  175.         o  stepping variables, generally between each execution of the loop
  176.           body
  177.  
  178.         o  performing termination tests, generally just before the execution of
  179.           the loop body
  180.  
  181. [change_end]
  182.  
  183. -------------------------------------------------------------------------------
  184.  
  185. 26.3.2. Kinds of Loop Clauses
  186.  
  187. [change_begin]
  188. Loop clauses fall into one of the following categories:
  189.  
  190.    *  variable initialization and stepping
  191.  
  192.         o  The for and as constructs provide iteration control clauses that
  193.           establish a variable to be initialized. You can combine for and as
  194.           clauses with the loop keyword and to get parallel initialization and
  195.           stepping.
  196.  
  197.         o  The with construct is similar to a single let clause. You can
  198.           combine with clauses using and to get parallel initialization.
  199.  
  200.         o  The repeat construct causes iteration to terminate after a specified
  201.           number of times. It uses an internal variable to keep track of the
  202.           number of iterations.
  203.  
  204.      You can specify data types for loop variables (see section 26.12.1). It is
  205.      an error to bind the same variable twice in any variable-binding clause of
  206.      a single loop expression. Such variables include local variables,
  207.      iteration control variables, and variables found by destructuring.
  208.  
  209.    *  value accumulation
  210.  
  211.         o  The collect construct takes one form in its clause and adds the
  212.           value of that form to the end of a list of values. By default, the
  213.           list of values is returned when the loop finishes.
  214.  
  215.         o  The append construct takes one form in its clause and appends the
  216.           value of that form to the end of a list of values. By default, the
  217.           list of values is returned when the loop finishes.
  218.  
  219.         o  The nconc construct is similar to append, but its list values are
  220.           concatenated as if by the Common Lisp function nconc. By default, the
  221.           list of values is returned when the loop finishes.
  222.  
  223.         o  The sum construct takes one form in its clause that must evaluate to
  224.           a number and adds that number into a running total. By default, the
  225.           cumulative sum is returned when the loop finishes.
  226.  
  227.         o  The count construct takes one form in its clause and counts the
  228.           number of times that the form evaluates to a non-nil value. By
  229.           default, the count is returned when the loop finishes.
  230.  
  231.         o  The minimize construct takes one form in its clause and determines
  232.           the minimum value obtained by evaluating that form. By default, the
  233.           minimum value is returned when the loop finishes.
  234.  
  235.         o  The maximize construct takes one form in its clause and determines
  236.           the maximum value obtained by evaluating that form. By default, the
  237.           maximum value is returned when the loop finishes.
  238.  
  239.    *  termination conditions
  240.  
  241.         o  The loop-finish Lisp macro terminates iteration and returns any
  242.           accumulated result. If specified, any finally clauses are evaluated.
  243.  
  244.         o  The for and as constructs provide a termination test that is
  245.           determined by the iteration control clause.
  246.  
  247.         o  The repeat construct causes termination after a specified number of
  248.           iterations.
  249.  
  250.         o  The while construct takes one form, a condition, and terminates the
  251.           iteration if the condition evaluates to nil. A while clause is
  252.           equivalent to the expression (if (not condition) (loop-finish)).
  253.  
  254.         o  The until construct is the inverse of while; it terminates the
  255.           iteration if the condition evaluates to any non-nil value. An until
  256.           clause is equivalent to the expression (if condition (loop-finish)).
  257.  
  258.         o  The always construct takes one form and terminates the loop if the
  259.           form ever evaluates to nil; in this case, it returns nil. Otherwise,
  260.           it provides a default return value of t.
  261.  
  262.         o  The never construct takes one form and terminates the loop if the
  263.           form ever evaluates to non-nil; in this case, it returns nil.
  264.           Otherwise, it provides a default return value of t.
  265.  
  266.         o  The thereis construct takes one form and terminates the loop if the
  267.           form ever evaluates to non-nil; in this case, it returns that value.
  268.  
  269.    *  unconditional execution
  270.  
  271.         o  The do construct simply evaluates all forms in its clause.
  272.  
  273.         o  The return construct takes one form and returns its value. It is
  274.           equivalent to the clause do (return value).
  275.  
  276.    *  conditional execution
  277.  
  278.         o  The if construct takes one form as a predicate and a clause that is
  279.           executed when the predicate is true. The clause can be a value
  280.           accumulation, unconditional, or another conditional clause; it can
  281.           also be any combination of such clauses connected by the loop keyword
  282.           and.
  283.  
  284.         o  The when construct is a synonym for if.
  285.  
  286.         o  The unless construct is similar to when except that it complements
  287.           the predicate; it executes the following clause if the predicate is
  288.           false.
  289.  
  290.         o  The else construct provides an optional component of if, when, and
  291.           unless clauses that is executed when the predicate is false. The
  292.           component is one of the clauses described under if.
  293.  
  294.         o  The end construct provides an optional component to mark the end of
  295.           a conditional clause.
  296.  
  297.    *  miscellaneous operations
  298.  
  299.         o  The named construct assigns a name to a loop construct.
  300.  
  301.         o  The initially construct causes its forms to be evaluated in the loop
  302.           prologue, which precedes all loop code except for initial settings
  303.           specified by the constructs with, for, or as.
  304.  
  305.         o  The finally construct causes its forms to be evaluated in the loop
  306.           epilogue after normal iteration terminates. An unconditional clause
  307.           can also follow the loop keyword finally.
  308.  
  309. [change_end]
  310.  
  311. -------------------------------------------------------------------------------
  312.  
  313. 26.3.3. Loop Syntax
  314.  
  315. [change_begin]
  316. The following syntax description provides an overview of the syntax for loop
  317. clauses. Detailed syntax descriptions of individual clauses appear in sections
  318. 26.6 through 26.12. A loop consists of the following types of clauses:
  319.  
  320. initial-final ::= initially | finally
  321. variables ::= with | initial-final | for-as | repeat
  322. main ::= unconditional | accumulation | conditional
  323.      | termination | initial-final
  324. loop ::= (loop [named name] {variables}* {main}*)
  325.  
  326. Note that a loop must have at least one clause; however, for backward
  327. compatibility, the following format is also supported:
  328.  
  329. (loop {tag | expr}*)
  330.  
  331. where expr is any Common Lisp expression that can be evaluated, and tag is any
  332. symbol not identifiable as a loop keyword. Such a format is roughly equivalent
  333. to the following one:
  334.  
  335. (loop do {tag | expr}*)
  336.  
  337. A loop prologue consists of any automatic variable initializations prescribed
  338. by the variable clauses, along with any initially clauses in the order they
  339. appear in the source.
  340.  
  341. A loop epilogue consists of finally clauses, if any, along with any implicit
  342. return value from an accumulation clause or an end-test clause.
  343.  
  344. [change_end]
  345. -------------------------------------------------------------------------------
  346.  
  347. 26.4. User Extensibility
  348.  
  349. [change_begin]
  350. There is currently no specified portable method for users to add extensions to
  351. the Loop Facility. The names defloop and define-loop-method have been suggested
  352. as candidates for such a method.
  353. [change_end]
  354.  
  355. -------------------------------------------------------------------------------
  356.  
  357. 26.5. Loop Constructs
  358.  
  359. [change_begin]
  360. The remaining sections of this chapter describe the constructs that the Loop
  361. Facility provides. The descriptions are organized according to the
  362. functionality of the constructs. Each section begins with a general discussion
  363. of a particular operation; it then presents the constructs that perform the
  364. operation.
  365.  
  366.    *  Section 26.6, ``Iteration Control,'' describes iteration control clauses
  367.      that allow directed loop iteration.
  368.  
  369.    *  Section 26.7, ``End-Test Control,'' describes clauses that stop iteration
  370.      by providing a conditional expression that can be tested after each
  371.      execution of the loop body.
  372.  
  373.    *  Section 26.8, ``Value Accumulation,'' describes constructs that
  374.      accumulate values during iteration and return them from a loop. This
  375.      section also discusses ways in which accumulation clauses can be combined
  376.      within the Loop Facility.
  377.  
  378.    *  Section 26.9, ``Variable Initializations,'' describes the with construct,
  379.      which provides local variables for use within the loop body, and other
  380.      constructs that provide local variables.
  381.  
  382.    *  Section 26.10, ``Conditional Execution,'' describes how to execute loop
  383.      clauses conditionally.
  384.  
  385.    *  Section 26.11, ``Unconditional Execution,'' describes the do and return
  386.      constructs. It also describes constructs that are used in the loop
  387.      prologue and loop epilogue.
  388.  
  389.    *  Section 26.12, ``Miscellaneous Features,'' discusses loop data types and
  390.      destructuring. It also presents constructs for naming a loop and for
  391.      specifying initial and final actions.
  392.  
  393. [change_end]
  394.  
  395. -------------------------------------------------------------------------------
  396.  
  397. 26.6. Iteration Control
  398.  
  399. [change_begin]
  400. Iteration control clauses allow you to direct loop iteration. The loop keywords
  401. as, for, and repeat designate iteration control clauses.
  402.  
  403. Iteration control clauses differ with respect to the specification of
  404. termination conditions and the initialization and stepping of loop variables.
  405. Iteration clauses by themselves do not cause the Loop Facility to return
  406. values, but they can be used in conjunction with value-accumulation clauses to
  407. return values (see section 26.8).
  408.  
  409. All variables are initialized in the loop prologue. The scope of the variable
  410. binding is lexical unless it is proclaimed special; thus, the variable can be
  411. accessed only by expressions that lie textually within the loop. Stepping
  412. assignments are made in the loop body before any other expressions are
  413. evaluated in the body.
  414.  
  415. The variable argument in iteration control clauses can be a destructuring list.
  416. A destructuring list is a tree whose non-null atoms are symbols that can be
  417. assigned a value (see section 26.12.2).
  418.  
  419. The iteration control clauses for, as, and repeat must precede any other loop
  420. clauses except initially, with, and named, since they establish variable
  421. bindings. When iteration control clauses are used in a loop, termination tests
  422. in the loop body are evaluated before any other loop body code is executed.
  423.  
  424. If you use multiple iteration clauses to control iteration, variable
  425. initialization and stepping occur sequentially by default. You can use the and
  426. construct to connect two or more iteration clauses when sequential binding and
  427. stepping are not necessary. The iteration behavior of clauses joined by and is
  428. analogous to the behavior of the Common Lisp macro do relative to do*.
  429.  
  430. [X3J13 voted in March 1989 (LOOP-AND-DISCREPANCY)   to correct a minor
  431. inconsistency in the original syntactic specification for loop. Only for and as
  432. clauses (not repeat clauses) may be joined by the and construct. The precise
  433. syntax is as follows.
  434.  
  435. for-as ::= {for | as} for-as-subclause {and for-as-subclause}*
  436. for-as-subclause ::= for-as-arithmetic | for-as-in-list
  437.                 | for-as-on-list | for-as-equals-then
  438.                 | for-as-across | for-as-hash | for-as-package
  439. for-as-arithmetic ::= var [type-spec] [{from | downfrom | upfrom} expr1 ]
  440.                 [{to | downto | upto | below | above} expr2]
  441.                 [by expr3]
  442. for-as-in-list ::= var [type-spec] in expr1 [by step-fun]
  443. for-as-on-list ::= var [type-spec] on expr1 [by step-fun]
  444. for-as-equals-then ::= var [type-spec] = expr1 [then step-fun]
  445. for-as-across ::= var [type-spec] across vector
  446. for-as-hash ::= var [type-spec] being {each | the}
  447.                 {hash-key | hash-keys | hash-value | hash-values}
  448.                 {in | of} hash-table
  449.                 [using ({hash-value | hash-key} other-var)]
  450. for-as-package ::= var [type-spec] being {each | the}
  451.                 for-as-package-keyword
  452.                 {in | of} package
  453. for-as-package-keyword ::= symbol | present-symbol | external-symbol
  454.                 | symbols | present-symbols | external-symbols
  455.  
  456. This correction made for and as clauses syntactically similar to with clauses.
  457. I have changed all examples in this chapter to reflect the corrected
  458. syntax.-GLS]
  459.  
  460. In the following example, the variable x is stepped before y is stepped; thus,
  461. the value of y reflects the updated value of x:
  462.  
  463. (loop for x from 1 to 9
  464.       for y = nil then x
  465.       collect (list x y))
  466.    => ((1 NIL) (2 2) (3 3) (4 4) (5 5) (6 6) (7 7) (8 8) (9 9))
  467.  
  468. In the following example, x and y are stepped in parallel:
  469.  
  470. (loop for x from 1 to 9
  471.       and y = nil then x
  472.       collect (list x y))
  473.    => ((1 NIL) (2 1) (3 2) (4 3) (5 4) (6 5) (7 6) (8 7) (9 8))
  474.  
  475. The for and as clauses iterate by using one or more local loop variables that
  476. are initialized to some value and that can be modified or stepped after each
  477. iteration. For these clauses, iteration terminates when a local variable
  478. reaches some specified value or when some other loop clause terminates
  479. iteration. At each iteration, variables can be stepped by an increment or a
  480. decrement or can be assigned a new value by the evaluation of an expression.
  481. Destructuring can be used to assign initial values to variables during
  482. iteration.
  483.  
  484. The for and as keywords are synonyms and may be used interchangeably. There are
  485. seven syntactic representations for these constructs. In each syntactic
  486. description, the data type of var can be specified by the optional type-spec
  487. argument. If var is a destructuring list, the data type specified by the
  488. type-spec argument must appropriately match the elements of the list (see
  489. sections 26.12.1 and 26.12.2).
  490.  
  491. [Loop Clause]
  492.  
  493. for var [type-spec] [{from | downfrom | upfrom} expr1]
  494.     [{to | downto | upto | below | above} expr2]
  495.     [by expr3]
  496. as var [type-spec] [{from | downfrom | upfrom} expr1]
  497.     [{to | downto | upto | below | above} expr2]
  498.     [by expr3]
  499.  
  500. [This is the first of seven for/as syntaxes.-GLS]
  501.  
  502. The for or as construct iterates from the value specified by expr1 to the value
  503. specified by expr2 in increments or decrements denoted by expr3. Each
  504. expression is evaluated only once and must evaluate to a number.
  505.  
  506. The variable var is bound to the value of expr1 in the first iteration and is
  507. stepped by the value of expr3 in each succeeding iteration, or by 1 if expr3 is
  508. not provided.
  509.  
  510. The following loop keywords serve as valid prepositions within this syntax.
  511.  
  512. from
  513.      The loop keyword from marks the value from which stepping begins, as
  514.      specified by expr1. Stepping is incremental by default. For decremental
  515.      stepping, use above or downto with expr2. For incremental stepping, the
  516.      default from value is 0.
  517.  
  518. downfrom, upfrom
  519.      The loop keyword downfrom indicates that the variable var is decreased in
  520.      decrements specified by expr3; the loop keyword upfrom indicates that var
  521.      is increased in increments specified by expr3.
  522.  
  523. to   The loop keyword to marks the end value for stepping specified in expr2.
  524.      Stepping is incremental by default. For decremental stepping, use downto,
  525.      downfrom, or above with expr2.
  526.  
  527. downto, upto
  528.      The loop keyword downto allows iteration to proceed from a larger number
  529.      to a smaller number by the decrement expr3. The loop keyword upto allows
  530.      iteration to proceed from a smaller number to a larger number by the
  531.      increment expr3. Since there is no default for expr1 in decremental
  532.      stepping, you must supply a value with downto.
  533.  
  534. below, above
  535.      The loop keywords below and above are analogous to upto and downto,
  536.      respectively. These keywords stop iteration just before the value of the
  537.      variable var reaches the value specified by expr2; the end value of expr2
  538.      is not included. Since there is no default for expr1 in decremental
  539.      stepping, you must supply a value with above.
  540.  
  541. by   The loop keyword by marks the increment or decrement specified by expr3.
  542.      The value of expr3 can be any positive number. The default value is 1.
  543.  
  544. At least one of these prepositions must be used with this syntax.
  545.  
  546. In an iteration control clause, the for or as construct causes termination when
  547. the specified limit is reached. That is, iteration continues until the value
  548. var is stepped to the exclusive or inclusive limit specified by expr2. The
  549. range is exclusive if expr3 increases or decreases var to the value of expr2
  550. without reaching that value; the loop keywords below and above provide
  551. exclusive limits. An inclusive limit allows var to attain the value of expr2;
  552. to, downto, and upto provide inclusive limits.
  553.  
  554. A common convention is to use for to introduce new iterations and as to
  555. introduce iterations that depend on a previous iteration specification.
  556. [However, loop does not enforce this convention, and some of the examples below
  557. violate it. De gustibus non disputandum est.-GLS]
  558.  
  559. Examples:
  560.  
  561. ;;; Print some numbers.
  562.  
  563. (loop as i from 1 to 5
  564.       do (print i)) `;Prints 5 lines
  565.  
  566.  
  567.  
  568.  
  569.  
  570.    => NIL
  571.  
  572. ;;; Print every third number.
  573.  
  574. (loop for i from 10 downto 1 by 3
  575.       do (print i)) `;Prints 4 lines
  576. 10
  577.  
  578.  
  579.  
  580.    => NIL
  581.  
  582. ;;; Step incrementally from the default starting value.
  583.  
  584. (loop as i below 5
  585.       do (print i)) `;Prints 5 lines
  586.  
  587.  
  588.  
  589.  
  590.  
  591.    => NIL
  592.  
  593. [Loop Clause]
  594. for var [type-spec] in expr1 [by step-fun]
  595. as var [type-spec] in expr1 [by step-fun]
  596.  
  597. [This is the second of seven for/as syntaxes.-GLS]
  598.  
  599. This construct iterates over the contents of a list. It checks for the end of
  600. the list as if using the Common Lisp function endp. The variable var is bound
  601. to the successive elements of the list expr1 before each iteration. At the end
  602. of each iteration, the function step-fun is called on the list and is expected
  603. to produce a successor list; the default value for step-fun is the cdr
  604. function.
  605.  
  606. The for or as construct causes termination when the end of the list is reached.
  607. The loop keywords in and by serve as valid prepositions in this syntax.
  608.  
  609. Examples:
  610.  
  611. ;;; Print every item in a list.
  612.  
  613. (loop for item in '(1 2 3 4 5) do (print item)) `;Prints 5 lines
  614.  
  615.  
  616.  
  617.  
  618.  
  619.    => NIL
  620.  
  621. ;;; Print every other item in a list.
  622.  
  623. (loop for item in '(1 2 3 4 5) by #'cddr
  624.       do (print item))  `;Prints 3 lines
  625.  
  626.  
  627.  
  628.    => NIL
  629.  
  630. ;;; Destructure items of a list, and sum the x values
  631. ;;; using fixnum arithmetic.
  632. (loop for (item . x) (t . fixnum)
  633.           in '((A . 1) (B . 2) (C . 3))
  634.       unless (eq item 'B) sum x)
  635.    => 4
  636.  
  637. [Loop Clause]
  638. for var [type-spec] on expr1 [by step-fun]
  639. as var [type-spec] on expr1 [by step-fun]
  640.  
  641. [This is the third of seven for/as syntaxes.-GLS]
  642.  
  643. This construct iterates over the contents of a list. It checks for the end of
  644. the list as if using the Common Lisp function endp. The variable var is bound
  645. to the successive tails of the list expr1. At the end of each iteration, the
  646. function step-fun is called on the list and is expected to produce a successor
  647. list; the default value for step-fun is the cdr function.
  648.  
  649. The loop keywords on and by serve as valid prepositions in this syntax. The for
  650. or as construct causes termination when the end of the list is reached.
  651.  
  652. Examples:
  653.  
  654. ;;; Collect successive tails of a list.
  655. (loop for sublist on '(a b c d)
  656.       collect sublist)
  657.    => ((A B C D) (B C D) (C D) (D))
  658.  
  659. ;;; Print a list by using destructuring with the loop keyword ON.
  660. (loop for (item) on '(1 2 3)
  661.       do (print item))  `;Prints 3 lines
  662.  
  663.  
  664.  
  665.    => NIL
  666.  
  667. ;;; Print items in a list without using destructuring.
  668. (loop for item in '(1 2 3)
  669.       do (print item))  `;Prints 3 lines
  670.  
  671.  
  672.  
  673.    => NIL
  674.  
  675. [Loop Clause]
  676. for var [type-spec] = expr1 [then expr2]
  677. as var [type-spec] = expr1 [then expr2]
  678.  
  679. [This is the fourth of seven for/as syntaxes.-GLS]
  680.  
  681. This construct initializes the variable var by setting it to the result of
  682. evaluating expr1 on the first iteration, then setting it to the result of
  683. evaluating expr2 on the second and subsequent iterations. If expr2 is omitted,
  684. the construct uses expr1 on the second and subsequent iterations. When expr2 is
  685. omitted, the expanded code shows the following optimization:
  686.  
  687. ;;; Sample original code:
  688. (loop for x = expr1 then expr2 do (print x))
  689.  
  690. ;;; The usual expansion:
  691. (tagbody
  692.       (setq x expr1)
  693.   tag (print x)
  694.       (setq x expr2)
  695.       (go tag))
  696.  
  697. ;;; The optimized expansion:
  698. (tagbody
  699.   tag (setq x expr1)
  700.       (print x)
  701.       (go tag))
  702.  
  703. The loop keywords = and then serve as valid prepositions in this syntax. This
  704. construct does not provide any termination conditions.
  705.  
  706. Example:
  707.  
  708. ;;; Collect some numbers.
  709. (loop for item = 1 then (+ item 10)
  710.       repeat 5
  711.       collect item)
  712.    => (1 11 21 31 41)
  713.  
  714. [Loop Clause]
  715. for var [type-spec] across vector
  716. as var [type-spec] across vector
  717.  
  718. [This is the fifth of seven for/as syntaxes.-GLS]
  719.  
  720. This construct binds the variable var to the value of each element in the array
  721. vector.
  722.  
  723. The loop keyword across marks the array vector; across is used as a preposition
  724. in this syntax. Iteration stops when there are no more elements in the
  725. specified array that can be referenced.
  726.  
  727. Some implementations might use a [user-supplied-GLS] the special form in the
  728. vector form to produce more efficient code.
  729.  
  730. Example:
  731.  
  732. (loop for char across (the simple-string (find-message port))
  733.       do (write-char char stream))
  734.  
  735. [Loop Clause]
  736.  
  737. for var [type-spec] being {each | the}
  738.     {hash-key | hash-keys | hash-value | hash-values}
  739.     {in | of} hash-table [using ({hash-value | hash-key} other-var)]
  740. as var [type-spec] being {each | the}
  741.     {hash-key | hash-keys | hash-value | hash-values}
  742.     {in | of} hash-table [using ({hash-value | hash-key} other-var)]
  743.  
  744. [This is the sixth of seven for/as syntaxes.-GLS]
  745.  
  746. This construct iterates over the elements, keys, and values of a hash table.
  747. The variable var takes on the value of each hash key or hash value in the
  748. specified hash table.
  749.  
  750. The following loop keywords serve as valid prepositions within this syntax.
  751.  
  752. being
  753.      The keyword being marks the loop method to be used, either hash-key or
  754.      hash-value.
  755.  
  756. each, the
  757.      For purposes of readability, the loop keyword each should follow the loop
  758.      keyword being when hash-key or hash-value is used. The loop keyword the is
  759.      used with hash-keys and hash-values.
  760.  
  761. hash-key, hash-keys
  762.      These loop keywords access each key entry of the hash table. If the name
  763.      hash-value is specified in a using construct with one of these loop
  764.      methods, the iteration can optionally access the keyed value. The order in
  765.      which the keys are accessed is undefined; empty slots in the hash table
  766.      are ignored.
  767.  
  768. hash-value, hash-values
  769.      These loop keywords access each value entry of a hash table. If the name
  770.      hash-key is specified in a using construct with one of these loop methods,
  771.      the iteration can optionally access the key that corresponds to the value.
  772.      The order in which the keys are accessed is undefined; empty slots in the
  773.      hash table are ignored.
  774.  
  775. using
  776.      The loop keyword using marks the optional key or the keyed value to be
  777.      accessed. It allows you to access the hash key if iterating over the hash
  778.      values, and the hash value if iterating over the hash keys.
  779.  
  780. in, of
  781.      These loop prepositions mark the hash table hash-table.
  782.  
  783. Iteration stops when there are no more hash keys or hash values to be
  784. referenced in the specified hash table.
  785.  
  786. [Loop Clause]
  787.  
  788. for var [type-spec] being {each | the}
  789.     {symbol | present-symbol | external-symbol |
  790.      symbols | present-symbols | external-symbols}
  791.     {in | of} package
  792. as var [type-spec] being {each | the}
  793.     {symbol | present-symbol | external-symbol |
  794.      symbols | present-symbols | external-symbols}
  795.     {in | of} package
  796.  
  797. [This is the last of seven for/as syntaxes.-GLS]
  798.  
  799. This construct iterates over the symbols in a package. The variable var takes
  800. on the value of each symbol in the specified package.
  801.  
  802. The following loop keywords serve as valid prepositions within this syntax.
  803.  
  804. being
  805.      The keyword being marks the loop method to be used: symbol,
  806.      present-symbol, or external-symbol.
  807.  
  808. each, the
  809.      For purposes of readability, the loop keyword each should follow the loop
  810.      keyword being when symbol, present-symbol, or external-symbol is used. The
  811.      loop keyword the is used with symbols, present-symbols, and
  812.      external-symbols.
  813.  
  814. present-symbol, present-symbols
  815.      These loop methods iterate over the symbols that are present but not
  816.      external in a package. The package to be iterated over is specified in the
  817.      same way that package arguments to the Common Lisp function find-package
  818.      are specified. If you do not specify the package for the iteration, the
  819.      current package is used. If you specify a package that does not exist, an
  820.      error is signaled.
  821.  
  822. symbol, symbols
  823.      These loop methods iterate over symbols that are accessible from a given
  824.      package. The package to be iterated over is specified in the same way that
  825.      package arguments to the Common Lisp function find-package are specified.
  826.      If you do not specify the package for the iteration, the current package
  827.      is used. If you specify a package that does not exist, an error is
  828.      signaled.
  829.  
  830. external-symbol, external-symbols
  831.      These loop methods iterate over the external symbols of a package. The
  832.      package to be iterated over is specified in the same way that package
  833.      arguments to the Common Lisp function find-package are specified. If you
  834.      do not specify the package for the iteration, the current package is used.
  835.      If you specify a package that does not exist, an error is signaled.
  836.  
  837. in, of
  838.      These loop prepositions mark the package package.
  839.  
  840. Iteration stops when there are no more symbols to be referenced in the
  841. specified package.
  842.  
  843. Example:
  844.  
  845. (loop for x being each present-symbol of "COMMON-LISP-USER"
  846.       do (print x)) `;Prints 7 lines in this example
  847. COMMON-LISP-USER::IN
  848. COMMON-LISP-USER::X
  849. COMMON-LISP-USER::ALWAYS
  850. COMMON-LISP-USER::FOO
  851. COMMON-LISP-USER::Y
  852. COMMON-LISP-USER::FOR
  853. COMMON-LISP-USER::LUCID
  854.    => NIL
  855.  
  856. [Loop Clause]
  857. repeat expr
  858.  
  859. The repeat construct causes iteration to terminate after a specified number of
  860. times. The loop body is executed n times, where n is the value of the
  861. expression expr. The expr argument is evaluated one time in the loop prologue.
  862. If the expression evaluates to zero or to a negative number, the loop body is
  863. not evaluated.
  864.  
  865. The clause repeat n is roughly equivalent to a clause such as
  866.  
  867. for internal-variable downfrom (- n 1) to 0
  868.  
  869. but, in some implementations, the repeat construct might be more efficient.
  870.  
  871. Examples:
  872.  
  873. (loop repeat 3 `;Prints 3 lines
  874.       do (format t "What I say three times is true~%"))
  875. What I say three times is true
  876. What I say three times is true
  877. What I say three times is true
  878.    => NIL
  879.  
  880. (loop repeat -15 `;Prints nothing
  881.       do (format t "What you see is what you expect~%"))
  882.    => NIL
  883.  
  884. [change_end]
  885.  
  886. -------------------------------------------------------------------------------
  887.  
  888. 26.7. End-Test Control
  889.  
  890. [change_begin]
  891. The loop keywords always, never, thereis, until, and while designate constructs
  892. that use a single test condition to determine when loop iteration should
  893. terminate.
  894.  
  895. The constructs always, never, and thereis provide specific values to be
  896. returned when a loop terminates. Using always, never, or thereis with
  897. value-returning accumulation clauses can produce unpredictable results. In all
  898. other respects these constructs behave like the while and until constructs.
  899.  
  900. The macro loop-finish can be used at any time to cause normal termination. In
  901. normal termination, finally clauses are executed and default return values are
  902. returned.
  903.  
  904. End-test control constructs can be used anywhere within the loop body. The
  905. termination conditions are tested in the order in which they appear.
  906.  
  907. [Loop Clause]
  908. while expr
  909. until expr
  910.  
  911. The while construct allows iteration to continue until the specified expression
  912. expr evaluates to nil. The expression is re-evaluated at the location of the
  913. while clause.
  914.  
  915. The until construct is equivalent to while (not expr). If the value of the
  916. specified expression is non-nil, iteration terminates.
  917.  
  918. You can use while and until at any point in a loop. If a while or until clause
  919. causes termination, any clauses that precede it in the source are still
  920. evaluated.
  921.  
  922. Examples:
  923.  
  924. ;;; A classic "while-loop".
  925. (loop while (hungry-p) do (eat))
  926.  
  927. ;;; UNTIL NOT is equivalent to WHILE.
  928. (loop until (not (hungry-p)) do (eat))
  929.  
  930. ;;; Collect the length and the items of STACK.
  931. (let ((stack '(a b c d e f)))
  932.   (loop while stack
  933.         for item = (length stack) then (pop stack)
  934.         collect item))
  935.    => (6 A B C D E F)
  936.  
  937. ;;; Use WHILE to terminate a loop that otherwise wouldn't
  938. ;;; terminate.  Note that WHILE occurs after the WHEN.
  939. (loop for i fixnum from 3
  940.       when (oddp i) collect i
  941.       while (< i 5))
  942.    => (3 5)
  943.  
  944. [Loop Clause]
  945. always expr
  946. never expr
  947. thereis expr
  948.  
  949. The always construct takes one form and terminates the loop if the form ever
  950. evaluates to nil; in this case, it returns nil. Otherwise, it provides a
  951. default return value of t.
  952.  
  953. The never construct takes one form and terminates the loop if the form ever
  954. evaluates to non-nil; in this case, it returns nil. Otherwise, it provides a
  955. default return value of t.
  956.  
  957. The thereis construct takes one form and terminates the loop if the form ever
  958. evaluates to non-nil; in this case, it returns that value.
  959.  
  960. If the while or until construct causes termination, control is passed to the
  961. loop epilogue, where any finally clauses will be executed. Since always, never,
  962. and thereis use the Common Lisp macro return to terminate iteration, any
  963. finally clause that is specified is not evaluated.
  964.  
  965. Examples:
  966.  
  967. ;;; Make sure I is always less than 11 (two ways).
  968. ;;; The FOR construct terminates these loops.
  969.  
  970. (loop for i from 0 to 10
  971.       always (< i 11))
  972.    => T
  973.  
  974. (loop for i from 0 to 10
  975.       never (> i 11))
  976.    => T
  977.  
  978. ;;; If I exceeds 10, return I; otherwise, return NIL.
  979. ;;; The THEREIS construct terminates this loop.
  980.  
  981. (loop for i from 0
  982.       thereis (when (> i 10) i) )
  983.    => 11
  984.  
  985. ;;; The FINALLY clause is not evaluated in these examples.
  986.  
  987. (loop for i from 0 to 10
  988.       always (< i 9)
  989.       finally (print "you won't see this"))
  990.    => NIL
  991.  
  992. (loop never t
  993.       finally (print "you won't see this"))
  994.    => NIL
  995.  
  996. (loop thereis "Here is my value"
  997.       finally (print "you won't see this"))
  998.    => "Here is my value"
  999.  
  1000. ;;; The FOR construct terminates this loop,
  1001. ;;; so the FINALLY clause is evaluated.
  1002.  
  1003. (loop for i from 1 to 10
  1004.       thereis (> i 11)
  1005.       finally (print i)) `;Prints 1 line
  1006. 11
  1007.    => NIL
  1008.  
  1009. (defstruct mountain height difficulty (why "because it is there"))
  1010. (setq everest (make-mountain :height '(2.86e-13 parsecs)))
  1011. (setq chocorua (make-mountain :height '(1059180001 microns)))
  1012. (defstruct desert area (humidity 0))
  1013. (setq sahara (make-desert :area '(212480000 square furlongs)))
  1014. `;First there is a mountain, then there is no mountain, then there is ...
  1015. (loop for x in (list everest sahara chocorua) `; -GLS
  1016.       thereis (and (mountain-p x) (mountain-height x)))
  1017.    => (2.86E-13 PARSECS)
  1018.  
  1019. ;;; If you could use this code to find a counterexample to
  1020. ;;; Fermat's last theorem, it would still not return the value
  1021. ;;; of the counterexample because all of the THEREIS clauses
  1022. ;;; in this example return only T.   Of course, this code has
  1023. ;;; never been observed to terminate.
  1024.  
  1025. (loop for z upfrom 2
  1026.       thereis
  1027.         (loop for n upfrom 3 below (log z 2)
  1028.               thereis
  1029.                 (loop for x below z
  1030.                       thereis
  1031.                         (loop for y below z
  1032.                               thereis (= (+ (expt x n)
  1033.                                             (expt y n))
  1034.                                          (expt z n))))))
  1035.  
  1036. [Macro]
  1037. loop-finish
  1038.  
  1039. The macro loop-finish terminates iteration normally and returns any accumulated
  1040. result. If specified, a finally clause is evaluated.
  1041.  
  1042. In most cases it is not necessary to use loop-finish because other loop control
  1043. clauses terminate the loop. Use loop-finish to provide a normal exit from a
  1044. nested condition inside a loop.
  1045.  
  1046. You can use loop-finish inside nested Lisp code to provide a normal exit from a
  1047. loop. Since loop-finish transfers control to the loop epilogue, using
  1048. loop-finish within a finally expression can cause infinite looping.
  1049.  
  1050. Implementations are allowed to provide this construct as a local macro by using
  1051. macrolet.
  1052.  
  1053. Examples:
  1054.  
  1055. ;;; Print a date in February, but exclude leap day.
  1056. ;;; LOOP-FINISH exits from the nested condition.
  1057. (loop for date in date-list
  1058.       do (case date
  1059.            (29 (when (eq month 'february)
  1060.                      (loop-finish))
  1061.              (format t "~:@(~A~) ~A" month date))))
  1062.  
  1063. ;;; Terminate the loop, but return the accumulated count.
  1064. (loop for i in '(1 2 3 stop-here 4 5 6)
  1065.       when (symbolp i) do (loop-finish)
  1066.       count i)
  1067.    => 3
  1068.  
  1069. ;;; This loop works just as well as the previous example.
  1070. (loop for i in '(1 2 3 stop-here 4 5 6)
  1071.       until (symbolp i)
  1072.       count i)
  1073.    => 3
  1074.  
  1075. [change_end]
  1076.  
  1077. -------------------------------------------------------------------------------
  1078.  
  1079. 26.8. Value Accumulation
  1080.  
  1081. [change_begin]
  1082. Accumulating values during iteration and returning them from a loop is often
  1083. useful. Some of these accumulations occur so frequently that special loop
  1084. clauses have been developed to handle them.
  1085.  
  1086. The loop keywords append, appending, collect, collecting, nconc, and nconcing
  1087. designate clauses that accumulate values in lists and return them.
  1088.  
  1089. The loop keywords count, counting, maximize, maximizing, minimize, minimizing,
  1090. sum, and summing designate clauses that accumulate and return numerical values.
  1091. [There is no semantic difference between the ``ing'' keywords and their
  1092. non-``ing'' counterparts. They are provided purely for the sake of stylistic
  1093. diversity among users. I happen to prefer the non-``ing'' forms-when I use loop
  1094. at all.-GLS]
  1095.  
  1096. The loop preposition into can be used to name the variable used to hold partial
  1097. accumulations. The variable is bound as if by the loop construct with (see
  1098. section 26.9). If into is used, the construct does not provide a default return
  1099. value; however, the variable is available for use in any finally clause.
  1100.  
  1101. You can combine value-returning accumulation clauses in a loop if all the
  1102. clauses accumulate the same type of data object. By default, the Loop Facility
  1103. returns only one value; thus, the data objects collected by multiple
  1104. accumulation clauses as return values must have compatible types. For example,
  1105. since both the collect and append constructs accumulate objects into a list
  1106. that is returned from a loop, you can combine them safely.
  1107.  
  1108. ;;; Collect every name and the kids in one list by using
  1109. ;;; COLLECT and APPEND.
  1110. (loop for name in '(fred sue alice joe june)
  1111.       for kids in '((bob ken) () () (kris sunshine) ())
  1112.       collect name
  1113.       append kids)
  1114.    => (FRED BOB KEN SUE ALICE JOE KRIS SUNSHINE JUNE)
  1115.  
  1116. [In the preceding example, note that the items accumulated by the collect and
  1117. append clauses are interleaved in the result list, according to the order in
  1118. which the clauses were executed.-GLS]
  1119.  
  1120. Multiple clauses that do not accumulate the same type of data object can
  1121. coexist in a loop only if each clause accumulates its values into a different
  1122. user-specified variable. Any number of values can be returned from a loop if
  1123. you use the Common Lisp function values, as the next example shows:
  1124.  
  1125. ;;; Count and collect names and ages.
  1126. (loop for name in '(fred sue alice joe june)
  1127.       as age in '(22 26 19 20 10)
  1128.       append (list name age) into name-and-age-list
  1129.       count name into name-count
  1130.       sum age into total-age
  1131.       finally
  1132.         (return (values (round total-age name-count)
  1133.                         name-and-age-list)))
  1134.    => 19 and (FRED 22 SUE 26 ALICE 19 JOE 20 JUNE 10)
  1135.  
  1136. [Loop Clause]
  1137. collect expr [into var]
  1138. collecting expr [into var]
  1139.  
  1140. During each iteration, these constructs collect the value of the specified
  1141. expression into a list. When iteration terminates, the list is returned.
  1142.  
  1143. The argument var is set to the list of collected values; if var is specified,
  1144. the loop does not return the final list automatically. If var is not specified,
  1145. it is equivalent to specifying an internal name for var and returning its value
  1146. in a finally clause. The var argument is bound as if by the construct with. You
  1147. cannot specify a data type for var; it must be of type list.
  1148.  
  1149. Examples:
  1150.  
  1151. ;;; Collect all the symbols in a list.
  1152. (loop for i in '(bird 3 4 turtle (1 . 4) horse cat)
  1153.       when (symbolp i) collect i)
  1154.    => (BIRD TURTLE HORSE CAT)
  1155.  
  1156. ;;; Collect and return odd numbers.
  1157. (loop for i from 1 to 10
  1158.       if (oddp i) collect i)
  1159.    => (1 3 5 7 9)
  1160.  
  1161. ;;; Collect items into local variable, but don't return them.
  1162. (loop for i in '(a b c d) by #'cddr
  1163.       collect i into my-list
  1164.       finally (print my-list)) `;Prints 1 line
  1165. (A C)
  1166.    => NIL
  1167.  
  1168. [Loop Clause]
  1169. append expr [into var]
  1170. appending expr [into var]
  1171. nconc expr [into var]
  1172. nconcing expr [into var]
  1173.  
  1174. These constructs are similar to collect except that the values of the specified
  1175. expression must be lists.
  1176.  
  1177. The append keyword causes its list values to be concatenated into a single
  1178. list, as if they were arguments to the Common Lisp function append.
  1179.  
  1180. The nconc keyword causes its list values to be concatenated into a single list,
  1181. as if they were arguments to the Common Lisp function nconc. Note that the
  1182. nconc keyword destructively modifies its argument lists.
  1183.  
  1184. The argument var is set to the list of concatenated values; if you specify var,
  1185. the loop does not return the final list automatically. The var argument is
  1186. bound as if by the construct with. You cannot specify a data type for var; it
  1187. must be of type list.
  1188.  
  1189. Examples:
  1190.  
  1191. ;;; Use APPEND to concatenate some sublists.
  1192. (loop for x in '((a) (b) ((c)))
  1193.       append x)
  1194.    => (A B (C))
  1195.  
  1196. ;;; NCONC some sublists together.  Note that only lists
  1197. ;;; made by the call to LIST are modified.
  1198. (loop for i upfrom 0
  1199.       as x in '(a b (c))
  1200.       nconc (if (evenp i) (list x) '()))
  1201.    => (A (C))
  1202.  
  1203. [Loop Clause]
  1204. count expr [into var] [type-spec]
  1205. counting expr [into var] [type-spec]
  1206.  
  1207. The count construct counts the number of times that the specified expression
  1208. has a non-nil value.
  1209.  
  1210. The argument var accumulates the number of occurrences; if var is specified,
  1211. the loop does not return the final count automatically. The var argument is
  1212. bound as if by the construct with.
  1213.  
  1214. If into var is used, the optional type-spec argument specifies a data type for
  1215. var. If there is no into variable, the optional type-spec argument applies to
  1216. the internal variable that is keeping the count. In either case it is an error
  1217. to specify a non-numeric data type. The default type is
  1218. implementation-dependent, but it must be a subtype of (or integer float).
  1219.  
  1220. Example:
  1221.  
  1222. (loop for i in '(a b nil c nil d e)
  1223.       count i)
  1224.    => 5
  1225.  
  1226. [Loop Clause]
  1227. sum expr [into var] [type-spec]
  1228. summing expr [into var] [type-spec]
  1229.  
  1230. The sum construct forms a cumulative sum of the values of the specified
  1231. expression at each iteration.
  1232.  
  1233. The argument var is used to accumulate the sum; if var is specified, the loop
  1234. does not return the final sum automatically. The var argument is bound as if by
  1235. the construct with.
  1236.  
  1237. If into var is used, the optional type-spec argument specifies a data type for
  1238. var. If there is no into variable, the optional type-spec argument applies to
  1239. the internal variable that is keeping the sum. In either case it is an error to
  1240. specify a non-numeric data type. The default type is implementation-dependent,
  1241. but it must be a subtype of number.
  1242.  
  1243. Examples:
  1244.  
  1245. ;;; Sum the elements of a list.
  1246.  
  1247. (loop for i fixnum in '(1 2 3 4 5)
  1248.       sum i)
  1249.    => 15
  1250.  
  1251. ;;; Sum a function of elements of a list.
  1252.  
  1253. (setq series
  1254.       '(1.2 4.3 5.7))
  1255.    => (1.2 4.3 5.7)
  1256.  
  1257. (loop for v in series
  1258.       sum (* 2.0 v))
  1259.    => 22.4
  1260.  
  1261. [Loop Clause]
  1262. maximize expr [into var] [type-spec]
  1263. maximizing expr [into var] [type-spec]
  1264. minimize expr [into var] [type-spec]
  1265. minimizing expr [into var] [type-spec]
  1266.  
  1267. The maximize construct compares the value of the specified expression obtained
  1268. during the first iteration with values obtained in successive iterations. The
  1269. maximum value encountered is determined and returned. If the loop never
  1270. executes the body, the returned value is not meaningful.
  1271.  
  1272. The minimize construct is similar to maximize; it determines and returns the
  1273. minimum value.
  1274.  
  1275. The argument var accumulates the maximum or minimum value; if var is specified,
  1276. the loop does not return the maximum or minimum automatically. The var argument
  1277. is bound as if by the construct with.
  1278.  
  1279. If into var is used, the optional type-spec argument specifies a data type for
  1280. var. If there is no into variable, the optional type-spec argument applies to
  1281. the internal variable that is keeping the intermediate result. In either case
  1282. it is an error to specify a non-numeric data type. The default type is
  1283. implementation-dependent, but it must be a subtype of (or integer float).
  1284.  
  1285. Examples:
  1286.  
  1287. (loop for i in '(2 1 5 3 4)
  1288.       maximize i)
  1289.    => 5
  1290.  
  1291. (loop for i in '(2 1 5 3 4)
  1292.       minimize i)
  1293.    => 1
  1294.  
  1295. ;;; In this example, FIXNUM applies to the internal
  1296. ;;; variable that holds the maximum value.
  1297.  
  1298. (setq series '(1.2 4.3 5.7))
  1299.    => (1.2 4.3 5.7)
  1300.  
  1301. (loop for v in series
  1302.       maximize (round v) fixnum)
  1303.    => 6
  1304.  
  1305. ;;; In this example, FIXNUM applies to the variable RESULT.
  1306.  
  1307. (loop for v float in series
  1308.       minimize (round v) into result fixnum
  1309.       finally (return result))
  1310.    => 1
  1311.  
  1312. [change_end]
  1313.  
  1314. -------------------------------------------------------------------------------
  1315.  
  1316. 26.9. Variable Initializations
  1317.  
  1318. [change_begin]
  1319. A local loop variable is one that exists only when the Loop Facility is
  1320. invoked. At that time, the variables are declared and are initialized to some
  1321. value. These local variables exist until loop iteration terminates, at which
  1322. point they cease to exist. Implicitly variables are also established by
  1323. iteration control clauses and the into preposition of accumulation clauses.
  1324.  
  1325. The loop keyword with designates a loop clause that allows you to declare and
  1326. initialize variables that are local to a loop. The variables are initialized
  1327. one time only; they can be initialized sequentially or in parallel.
  1328.  
  1329. By default, the with construct initializes variables sequentially; that is, one
  1330. variable is assigned a value before the next expression is evaluated. However,
  1331. by using the loop keyword and to join several with clauses, you can force
  1332. initializations to occur in parallel; that is, all of the specified expressions
  1333. are evaluated, and the results are bound to the respective variables
  1334. simultaneously.
  1335.  
  1336. Use sequential binding for making the initialization of some variables depend
  1337. on the values of previously bound variables. For example, suppose you want to
  1338. bind the variables a, b, and c in sequence:
  1339.  
  1340. (loop with a = 1
  1341.       with b = (+ a 2)
  1342.       with c = (+ b 3)
  1343.       with d = (+ c 4)
  1344.       return (list a b c d))
  1345.    => (1 3 6 10)
  1346.  
  1347. The execution of the preceding loop is equivalent to the execution of the
  1348. following code:
  1349.  
  1350. (let* ((a 1)
  1351.        (b (+ a 2))
  1352.        (c (+ b 3))
  1353.        (d (+ c 4)))
  1354.   (block nil
  1355.     (tagbody
  1356.       next-loop (return (list a b c d))
  1357.                 (go next-loop)
  1358.       end-loop)))
  1359.  
  1360. If you are not depending on the value of previously bound variables for the
  1361. initialization of other local variables, you can use parallel bindings as
  1362. follows:
  1363.  
  1364. (loop with a = 1
  1365.        and b = 2
  1366.        and c = 3
  1367.        and d = 4
  1368.       return (list a b c d))
  1369.    => (1 2 3 4)
  1370.  
  1371. The execution of the preceding loop is equivalent to the execution of the
  1372. following code:
  1373.  
  1374. (let ((a 1)
  1375.       (b 2)
  1376.       (c 3)
  1377.       (d 4))
  1378.   (block nil
  1379.     (tagbody
  1380.       next-loop (return (list a b c))
  1381.                 (go next-loop)
  1382.       end-loop)))
  1383.  
  1384. [Loop Clause]
  1385. with var [type-spec] [= expr] {and var [type-spec] [= expr]}*
  1386.  
  1387. The with construct initializes variables that are local to a loop. The
  1388. variables are initialized one time only.
  1389.  
  1390. If the optional type-spec argument is specified for any variable var, but there
  1391. is no related expression expr to be evaluated, var is initialized to an
  1392. appropriate default value for its data type. For example, for the data types t,
  1393. number, and float, the default values are nil, 0, and 0.0, respectively. It is
  1394. an error to specify a type-spec argument for var if the related expression
  1395. returns a value that is not of the specified type. The optional and clause
  1396. forces parallel rather than sequential initializations.
  1397.  
  1398. Examples:
  1399.  
  1400. ;;; These bindings occur in sequence.
  1401. (loop with a = 1
  1402.       with b = (+ a 2)
  1403.       with c = (+ b 3)
  1404.       with d = (+ c 4)
  1405.       return (list a b c d))
  1406.    => (1 3 6 10)
  1407.  
  1408. ;;; These bindings occur in parallel.
  1409. (setq a 5 b 10 c 1729)
  1410. (loop with a = 1
  1411.        and b = (+ a 2)
  1412.        and c = (+ b 3)
  1413.        and d = (+ c 4)
  1414.       return (list a b c d))
  1415.    => (1 7 13 1733)
  1416.  
  1417. ;;; This example shows a shorthand way to declare
  1418. ;;; local variables that are of different types.
  1419. (loop with (a b c) (float integer float)
  1420.       return (format nil "~A ~A ~A" a b c))
  1421.    => "0.0 0 0.0"
  1422.  
  1423. ;;; This example shows a shorthand way to declare
  1424. ;;; local variables that are of the same type.
  1425. (loop with (a b c) float
  1426.       return (format nil "~A ~A ~A" a b c))
  1427.    => "0.0 0.0 0.0"
  1428.  
  1429. [change_end]
  1430.  
  1431. -------------------------------------------------------------------------------
  1432.  
  1433. 26.10. Conditional Execution
  1434.  
  1435. [change_begin]
  1436. The loop keywords if, when, and unless designate constructs that are useful
  1437. when you want some loop clauses to operate under a specified condition.
  1438.  
  1439. If the specified condition is true, the succeeding loop clause is executed. If
  1440. the specified condition is not true, the succeeding clause is skipped, and
  1441. program control moves to the clause that follows the loop keyword else. If the
  1442. specified condition is not true and no else clause is specified, the entire
  1443. conditional construct is skipped. Several clauses can be connected into one
  1444. compound clause with the loop keyword and. The end of the conditional clause
  1445. can be marked with the keyword end.
  1446.  
  1447. [Loop Clause]
  1448.  
  1449. if expr clause {and clause}*
  1450.    [else clause {and clause}*] [end]
  1451. when expr clause {and clause}*
  1452.    [else clause {and clause}*] [end]
  1453. unless expr clause {and clause}*
  1454.    [else clause {and clause}*] [end]
  1455.  
  1456. The constructs when and if allow conditional execution of loop clauses. These
  1457. constructs are synonyms and can be used interchangeably. [Compare this to the
  1458. macro when, which does not allow an ``else'' part.-GLS]
  1459.  
  1460. If the value of the test expression expr is non-nil, the expression clause1 is
  1461. evaluated. If the test expression evaluates to nil and an else construct is
  1462. specified, the statements that follow the else are evaluated; otherwise,
  1463. control passes to the next clause.
  1464.  
  1465. The unless construct is equivalent to when (not expr) and if (not expr). If the
  1466. value of the test expression expr is nil, the expression clause1 is evaluated.
  1467. If the test expression evaluates to non-nil and an else construct is specified,
  1468. the statements that follow the else are evaluated; otherwise, control passes to
  1469. the next clause. [Compare this to the macro unless, which does not allow an
  1470. ``else'' part-or do I mean a ``then'' part?! Ugh. To prevent confusion, I
  1471. strongly recommend as a matter of style that else not be used with unless loop
  1472. clauses.-GLS]
  1473.  
  1474. The clause arguments must be either accumulation, unconditional, or conditional
  1475. clauses (see section 26.3.2). Clauses that follow the test expression can be
  1476. grouped by using the loop keyword and to produce a compound clause.
  1477.  
  1478. The loop keyword it can be used to refer to the result of the test expression
  1479. in a clause. If multiple clauses are connected with and, the it construct must
  1480. be used in the first clause in the block. Since it is a loop keyword, it may
  1481. not be used as a local variable within a loop.
  1482.  
  1483. If when or if clauses are nested, each else is paired with the closest
  1484. preceding when or if construct that has no associated else.
  1485.  
  1486. The optional loop keyword end marks the end of the clause. If this keyword is
  1487. not specified, the next loop keyword marks the end. You can use end to
  1488. distinguish the scoping of compound clauses.
  1489.  
  1490. ;;; Group conditional clauses into a block.
  1491. (loop for i in numbers-list
  1492.       when (oddp i)
  1493.         do (print i)
  1494.         and collect i into odd-numbers
  1495.         and do (terpri)
  1496.       else     ;I is even
  1497.         collect i into even-numbers
  1498.       finally
  1499.         (return (values odd-numbers even-numbers)))
  1500.  
  1501. ;;; Collect numbers larger than 3.
  1502. (loop for i in '(1 2 3 4 5 6)
  1503.       when (and (> i 3) i)
  1504.       collect it)     ;it refers to (and (> i 3) i)
  1505.    => (4 5 6)
  1506.  
  1507. ;;; Find a number in a list.
  1508. (loop for i in '(1 2 3 4 5 6)
  1509.       when (and (> i 3) i)
  1510.       return it)
  1511.    => 4
  1512.  
  1513. ;;; The preceding example is similar to the following one.
  1514. (loop for i in '(1 2 3 4 5 6)
  1515.       thereis (and (> i 3) i))
  1516.    => 4
  1517.  
  1518. ;;; An example of using UNLESS with ELSE (yuk).`-GLS
  1519. (loop for turtle in teenage-mutant-ninja-turtles do
  1520.   (loop for x in '(joker brainiac shredder krazy-kat)
  1521.         unless (evil x)
  1522.           do (eat (make-pizza :anchovies t))
  1523.         else unless (and (eq x 'shredder) (attacking-p x))
  1524.                do (cut turtle slack);When the evil Shredder attacks,
  1525.              else (fight turtle x)));those turtle boys don't cut no slack
  1526.  
  1527. ;;; Nest conditional clauses.
  1528. (loop for i in list
  1529.       when (numberp i)
  1530.         when (bignump i)
  1531.           collect i into big-numbers
  1532.         else     ;Not (bignump i)
  1533.           collect i into other-numbers
  1534.       else     ;Not (numberp i)
  1535.         when (symbolp i)
  1536.           collect i into symbol-list
  1537.         else     ;Not (symbolp i)
  1538.           (error "found a funny value in list ~S, value ~S~%"
  1539.                 "list i))
  1540.  
  1541. ;;; Without the END marker, the last AND would apply to the
  1542. ;;; inner IF rather than the outer one.
  1543. (loop for x from 0 to 3
  1544.       do (print x)
  1545.       if (zerop (mod x 2))
  1546.         do (princ " a")
  1547.           and if (zerop (floor x 2))
  1548.                 do (princ " b")
  1549.               end
  1550.           and do (princ " c"))
  1551.  
  1552. [change_end]
  1553.  
  1554. -------------------------------------------------------------------------------
  1555.  
  1556. 26.11. Unconditional Execution
  1557.  
  1558. [change_begin]
  1559. The loop construct do (or doing) takes one or more expressions and simply
  1560. evaluates them in order.
  1561.  
  1562. The loop construct return takes one expression and returns its value. It is
  1563. equivalent to the clause do (return value).
  1564.  
  1565. [Loop Clause]
  1566. do {expr}*
  1567. doing {expr}*
  1568.  
  1569. The do construct simply evaluates the specified expressions wherever they occur
  1570. in the expanded form of loop.
  1571.  
  1572. The expr argument can be any non-atomic Common Lisp form. Each expr is
  1573. evaluated in every iteration.
  1574.  
  1575. The constructs do, initially, and finally are the only loop keywords that take
  1576. an arbitrary number of forms and group them as if using an implicit progn.
  1577. Because every loop clause must begin with a loop keyword, you would use the
  1578. keyword do when no control action other than execution is required.
  1579.  
  1580. Examples:
  1581.  
  1582. ;;; Print some numbers.
  1583. (loop for i from 1 to 5
  1584.       do (print i)) `;Prints 5 lines
  1585.  
  1586.  
  1587.  
  1588.  
  1589.  
  1590.    => NIL
  1591.  
  1592. ;;; Print numbers and their squares.
  1593. ;;; The DO construct applies to multiple forms.
  1594. (loop for i from 1 to 4
  1595.       do (print i)
  1596.          (print (* i i))) `;Prints 8 lines
  1597.  
  1598.  
  1599.  
  1600.  
  1601.  
  1602.  
  1603.  
  1604. 16
  1605.    => NIL
  1606.  
  1607. [Loop Clause]
  1608. return expr
  1609.  
  1610. The return construct terminates a loop and returns the value of the specified
  1611. expression as the value of the loop. This construct is similar to the Common
  1612. Lisp special form return-from and the Common Lisp macro return.
  1613.  
  1614. The Loop Facility supports the return construct for backward compatibility with
  1615. older loop implementations. The return construct returns immediately and does
  1616. not execute any finally clause that is given.
  1617.  
  1618. Examples:
  1619.  
  1620. ;;; Signal an exceptional condition.
  1621. (loop for item in '(1 2 3 a 4 5)
  1622.       when (not (numberp item))
  1623.       return (cerror "enter new value"
  1624.                      "non-numeric value: ~s"
  1625.                      item)) `;Signals an error
  1626. >>Error: non-numeric value: A
  1627.  
  1628. ;;; The previous example is equivalent to the following one.
  1629. (loop for item in '(1 2 3 a 4 5)
  1630.      when (not (numberp item))
  1631.       do (return
  1632.            (cerror "enter new value"
  1633.                    "non-numeric value: ~s"
  1634.                    item)))  `;Signals an error
  1635. >>Error: non-numeric value: A
  1636.  
  1637. [change_end]
  1638.  
  1639. -------------------------------------------------------------------------------
  1640.  
  1641. 26.12. Miscellaneous Features
  1642.  
  1643. [change_begin]
  1644. The Loop Facility provides the named construct to name a loop so that the
  1645. Common Lisp special form return-from can be used.
  1646.  
  1647. The loop keywords initially and finally designate loop constructs that cause
  1648. expressions to be evaluated before and after the loop body, respectively.
  1649.  
  1650. The code for any initially clauses is collected into one progn in the order in
  1651. which the clauses appeared in the loop. The collected code is executed once in
  1652. the loop prologue after any implicit variable initializations.
  1653.  
  1654. The code for any finally clauses is collected into one progn in the order in
  1655. which the clauses appeared in the loop. The collected code is executed once in
  1656. the loop epilogue before any implicit values are returned from the accumulation
  1657. clauses. Explicit returns in the loop body, however, will exit the loop without
  1658. executing the epilogue code.
  1659.  
  1660. [change_end]
  1661. -------------------------------------------------------------------------------
  1662.  
  1663.    *  Data Types
  1664.    *  Destructuring
  1665.  
  1666. -------------------------------------------------------------------------------
  1667.  
  1668. 26.12.1. Data Types
  1669.  
  1670. [change_begin]
  1671. Many loop constructs take a type-spec argument that allows you to specify
  1672. certain data types for loop variables. While it is not necessary to specify a
  1673. data type for any variable, by doing so you ensure that the variable has a
  1674. correctly typed initial value. The type declaration is made available to the
  1675. compiler for more efficient loop expansion. In some implementations, fixnum and
  1676. float declarations are especially useful; the compiler notices them and emits
  1677. more efficient code.
  1678.  
  1679. The type-spec argument has the following syntax:
  1680.  
  1681. type-spec ::= of-type d-type-spec
  1682. d-type-spec ::= type-specifier | (d-type-spec . d-type-spec)
  1683.  
  1684. A type-specifier in this syntax can be any Common Lisp type specifier. The
  1685. d-type-spec argument is used for destructuring, as described in section
  1686. 26.12.2. If the d-type-spec argument consists solely of the types fixnum,
  1687. float, t, or nil, the of-type keyword is optional. The of-type construct is
  1688. optional in these cases to provide backward compatibility; thus the following
  1689. two expressions are the same:
  1690.  
  1691. ;;; This expression uses the old syntax for type specifiers.
  1692. (loop for i fixnum upfrom 3 ...)
  1693. ;;; This expression uses the new syntax for type specifiers.
  1694. (loop for i of-type fixnum upfrom 3 ...)
  1695.  
  1696. [change_end]
  1697.  
  1698. -------------------------------------------------------------------------------
  1699.  
  1700. 26.12.2. Destructuring
  1701.  
  1702. [change_begin]
  1703. Destructuring allows you to bind a set of variables to a corresponding set of
  1704. values anywhere that you can normally bind a value to a single variable. During
  1705. loop expansion, each variable in the variable list is matched with the values
  1706. in the values list. If there are more variables in the variable list than there
  1707. are values in the values list, the remaining variables are given a value of
  1708. nil. If there are more values than variables listed, the extra values are
  1709. discarded.
  1710.  
  1711. Suppose you want to assign values from a list to the variables a, b, and c. You
  1712. could use one for clause to bind the variable numlist to the car of the
  1713. specified expression, and then you could use another for clause to bind the
  1714. variables a, b, and c sequentially.
  1715.  
  1716. ;;; Collect values by using FOR constructs.
  1717. (loop for numlist in '((1 2 4.0) (5 6 8.3) (8 9 10.4))
  1718.       for a integer = (first numlist)
  1719.       and for b integer = (second numlist)
  1720.       and for c float = (third numlist)
  1721.       collect (list c b a))
  1722.    => ((4.0 2 1) (8.3 6 5) (10.4 9 8))
  1723.  
  1724. Destructuring makes this process easier by allowing the variables to be bound
  1725. in parallel in each loop iteration. You can declare data types by using a list
  1726. of type-spec arguments. If all the types are the same, you can use a shorthand
  1727. destructuring syntax, as the second example following illustrates.
  1728.  
  1729. ;;; Destructuring simplifies the process.
  1730. (loop for (a b c) (integer integer float) in
  1731.       '((1 2 4.0) (5 6 8.3) (8 9 10.4))
  1732.       collect (list c b a)))
  1733.    => ((4.0 2 1) (8.3 6 5) (10.4 9 8))
  1734.  
  1735. ;;; If all the types are the same, this way is even simpler.
  1736. (loop for (a b c) float in
  1737.       '((1.0 2.0 4.0) (5.0 6.0 8.3) (8.0 9.0 10.4))
  1738.       collect (list c b a))
  1739.    => ((4.0 2.0 1.0) (8.3 6.0 5.0) (10.4 9.0 8.0))
  1740.  
  1741. If you use destructuring to declare or initialize a number of groups of
  1742. variables into types, you can use the loop keyword and to simplify the process
  1743. further.
  1744.  
  1745. ;;; Initialize and declare variables in parallel
  1746. ;;; by using the AND construct.
  1747. (loop with (a b) float = '(1.0 2.0)
  1748.       and (c d) integer = '(3 4)
  1749.       and (e f)
  1750.       return (list a b c d e f))
  1751.    => (1.0 2.0 3 4 NIL NIL)
  1752.  
  1753. A data type specifier for a destructuring pattern is a tree of type specifiers
  1754. with the same shape as the tree of variables, with the following exceptions:
  1755.  
  1756.    *  When aligning the trees, an atom in the type specifier tree that matches
  1757.      a cons in the variable tree declares the same type for each variable.
  1758.  
  1759.    *  A cons in the type specifier tree that matches an atom in the variable
  1760.      tree is a non-atomic type specifer.
  1761.  
  1762. ;;; Declare X and Y to be of type VECTOR and FIXNUM, respectively.
  1763. (loop for (x y) of-type (vector fixnum) in my-list do ...)
  1764.  
  1765. If nil is used in a destructuring list, no variable is provided for its place.
  1766.  
  1767. (loop for (a nil b) = '(1 2 3)
  1768.       do (return (list a b)))
  1769.    => (1 3)
  1770.  
  1771. Note that nonstandard lists can specify destructuring.
  1772.  
  1773. (loop for (x . y) = '(1 . 2)
  1774.       do (return y))
  1775.    => 2
  1776.  
  1777. (loop for ((a . b) (c . d))
  1778.           of-type ((float . float) (integer . integer))
  1779.           in '(((1.2 . 2.4) (3 . 4)) ((3.4 . 4.6) (5 . 6)))
  1780.       collect (list a b c d))
  1781.    => ((1.2 2.4 3 4) (3.4 4.6 5 6))
  1782.  
  1783. [It is worth noting that the destructuring facility of loop predates, and
  1784. differs in some details from, that of destructuring-bind, an extension that has
  1785. been provided by many implementors of Common Lisp.-GLS]
  1786.  
  1787. [Loop Clause]
  1788. initially {expr}*
  1789. finally [do | doing] {expr}*
  1790. finally return expr
  1791.  
  1792. The initially construct causes the specified expression to be evaluated in the
  1793. loop prologue, which precedes all loop code except for initial settings
  1794. specified by constructs with, for, or as. The finally construct causes the
  1795. specified expression to be evaluated in the loop epilogue after normal
  1796. iteration terminates.
  1797.  
  1798. The expr argument can be any non-atomic Common Lisp form.
  1799.  
  1800. Clauses such as return, always, never, and thereis can bypass the finally
  1801. clause.
  1802.  
  1803. The Common Lisp macro return (or the return loop construct) can be used after
  1804. finally to return values from a loop. The evaluation of the return form inside
  1805. the finally clause takes precedence over returning the accumulation from
  1806. clauses specified by such keywords as collect, nconc, append, sum, count,
  1807. maximize, and minimize; the accumulation values for these pre-empted clauses
  1808. are not returned by the loop if return is used.
  1809.  
  1810. The constructs do, initially, and finally are the only loop keywords that take
  1811. an arbitrary number of (non-atomic) forms and group them as if by using an
  1812. implicit progn.
  1813.  
  1814. Examples:
  1815.  
  1816. ;;; This example parses a simple printed string representation
  1817. ;;; from BUFFER (which is itself a string) and returns the
  1818. ;;; index of the closing double-quote character.
  1819.  
  1820. (loop initially (unless (char= (char buffer 0) #¥")
  1821.                   (loop-finish))
  1822.       for i fixnum from 1 below (string-length buffer)
  1823.       when (char= (char buffer i) #¥")
  1824.         return i)
  1825.  
  1826. ;;; The FINALLY clause prints the last value of I.
  1827. ;;; The collected value is returned.
  1828.  
  1829. (loop for i from 1 to 10
  1830.       when (> i 5)
  1831.         collect i
  1832.       finally (print i)) `;Prints 1 line
  1833. 11
  1834.    => (6 7 8 9 10)
  1835.  
  1836. ;;; Return both the count of collected numbers
  1837. ;;; as well as the numbers themselves.
  1838.  
  1839. (loop for i from 1 to 10
  1840.       when (> i 5)
  1841.         collect i into number-list
  1842.         and count i into number-count
  1843.       finally (return (values number-count number-list)))
  1844.    => 5 and (6 7 8 9 10)
  1845.  
  1846. [Loop Clause]
  1847. named name
  1848.  
  1849. The named construct allows you to assign a name to a loop construct so that you
  1850. can use the Common Lisp special form return-from to exit the named loop.
  1851.  
  1852. Only one name may be assigned per loop; the specified name becomes the name of
  1853. the implicit block for the loop.
  1854.  
  1855. If used, the named construct must be the first clause in the loop expression,
  1856. coming right after the word loop.
  1857.  
  1858. Example:
  1859.  
  1860. ;;; Just name and return.
  1861. (loop named max
  1862.       for i from 1 to 10
  1863.       do (print i)
  1864.       do (return-from max 'done)) `;Prints 1 line
  1865.  
  1866.    => DONE
  1867.  
  1868. [change_end]
  1869.  
  1870. -------------------------------------------------------------------------------
  1871.  
  1872.  
  1873.  
  1874.  
  1875.